Integracija TypeScripta i Expressa: Sigurnost tipa u rukovateljima ruta

TypeScript je postao kamen temeljac modernog JavaScript razvoja, nudeći mogućnosti statičkog tipiziranja koje poboljšavaju kvalitetu koda, održivost i skalabilnost. U kombinaciji s Express.js-om, popularnim Node.js okvirom za web aplikacije, TypeScript može značajno poboljšati robusnost vaših pozadinskih API-ja. Ovaj sveobuhvatan vodič istražuje kako iskoristiti TypeScript za postizanje sigurnosti tipa u rukovateljima ruta u Express.js aplikacijama, pružajući praktične primjere i najbolje prakse za izgradnju robusnih i održivih API-ja za globalnu publiku.

Zašto je sigurnost tipa važna u Express.js-u

U dinamičkim jezicima poput JavaScripta, pogreške se često otkrivaju tijekom izvođenja, što može dovesti do neočekivanog ponašanja i teško otklonjivih problema. TypeScript to rješava uvođenjem statičkog tipiziranja, omogućujući vam da uhvatite pogreške tijekom razvoja prije nego što dospiju u produkciju. U kontekstu Express.js-a, sigurnost tipa je posebno ključna za rukovatelje ruta, gdje radite s objektima zahtjeva i odgovora, parametara upita i tijelima zahtjeva. Neispravno rukovanje tim elementima može dovesti do padova aplikacije, oštećenja podataka i sigurnosnih ranjivosti.

• Rano otkrivanje pogrešaka: Uhvatite pogreške povezane s tipom tijekom razvoja, smanjujući vjerojatnost iznenađenja tijekom izvođenja.
• Poboljšana održivost koda: Bilješke tipova čine kod lakšim za razumijevanje i refaktoriranje.
• Poboljšano automatsko dovršavanje koda i alati: IDE-ovi mogu pružiti bolje prijedloge i provjeru pogrešaka s informacijama o tipovima.
• Smanjenje grešaka: Sigurnost tipa pomaže u sprječavanju uobičajenih programskih pogrešaka, poput prosljeđivanja netočnih tipova podataka funkcijama.

Postavljanje TypeScript Express.js projekta

Prije nego što zaronimo u sigurnost tipa rukovatelja ruta, postavimo osnovni TypeScript Express.js projekt. To će poslužiti kao temelj za naše primjere.

Preduvjeti

• Instaliran Node.js i npm (Node Package Manager). Možete ih preuzeti s službene web stranice Node.js-a. Provjerite imate li nedavnu verziju za optimalnu kompatibilnost.
• Uređivač koda poput Visual Studio Codea, koji nudi izvrsnu podršku za TypeScript.

Inicijalizacija projekta

1. Kreirajte novi direktorij projekta: mkdir typescript-express-app && cd typescript-express-app
2. Inicijalizirajte novi npm projekt: npm init -y
3. Instalirajte TypeScript i Express.js: npm install typescript express
4. Instalirajte TypeScript deklaracijske datoteke za Express.js (važno za sigurnost tipa): npm install @types/express @types/node
5. Inicijalizirajte TypeScript: npx tsc --init (Ovo stvara datoteku tsconfig.json, koja konfigurira TypeScript kompajler.)

Konfiguriranje TypeScripta

Otvorite datoteku tsconfig.json i konfigurirajte je na odgovarajući način. Evo primjera konfiguracije:

{
  "compilerOptions": {
    "target": "es6",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

Ključne konfiguracije koje treba napomenuti:

• target: Određuje ciljanu ECMAScript verziju. es6 je dobra početna točka.
• module: Određuje generiranje koda modula. commonjs je čest izbor za Node.js.
• outDir: Određuje izlazni direktorij za kompilirane JavaScript datoteke.
• rootDir: Određuje korijenski direktorij vaših TypeScript izvornih datoteka.
• strict: Omogućuje sve opcije stroge provjere tipa za poboljšanu sigurnost tipa. Ovo se toplo preporučuje.
• esModuleInterop: Omogućuje interoperabilnost između CommonJS i ES modula.

Stvaranje ulazne točke

Kreirajte direktorij src i dodajte datoteku index.ts:

mkdir src
touch src/index.ts

Popunite src/index.ts s osnovnom postavkom Express.js servera:

import express, { Request, Response } from 'express';

const app = express();
const port = 3000;

app.get('/', (req: Request, res: Response) => {
  res.send('Hello, TypeScript Express!');
});

app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
});

Dodavanje skripte za izgradnju

Dodajte skriptu za izgradnju u svoju datoteku package.json za kompilaciju TypeScript koda:

"scripts": {
  "build": "tsc",
  "start": "node dist/index.js",
  "dev": "npm run build && npm run start"
}

Sada možete pokrenuti npm run dev za izgradnju i pokretanje servera.

Sigurnost tipa rukovatelja ruta: Definiranje tipova zahtjeva i odgovora

Srž sigurnosti tipa rukovatelja ruta leži u pravilnom definiranju tipova za objekte Request i Response. Express.js pruža generičke tipove za ove objekte koji vam omogućuju specificiranje tipova parametara upita, tijela zahtjeva i parametara rute.

Osnovni tipovi rukovatelja ruta

Započnimo s jednostavnim rukovateljem ruta koji očekuje ime kao parametar upita:

import express, { Request, Response } from 'express';

const app = express();
const port = 3000;

interface NameQuery {
  name: string;
}

app.get('/hello', (req: Request<any, any, any, NameQuery>, res: Response) => {
  const name = req.query.name;

  if (!name) {
    return res.status(400).send('Name parameter is required.');
  }

  res.send(`Hello, ${name}!`);
});

app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
});

U ovom primjeru:

• Request<any, any, any, NameQuery> definira tip za objekt zahtjeva.
• Prvi any predstavlja parametre rute (npr. /users/:id).
• Drugi any predstavlja tip tijela odgovora.
• Treći any predstavlja tip tijela zahtjeva.
• NameQuery je sučelje koje definira strukturu parametara upita.

Definiranjem sučelja NameQuery, TypeScript sada može provjeriti postoji li svojstvo req.query.name i je li tipa string. Ako pokušate pristupiti nepostojećem svojstvu ili dodijeliti vrijednost pogrešnog tipa, TypeScript će označiti pogrešku.

Rukovanje tijelima zahtjeva

Za rute koje prihvaćaju tijela zahtjeva (npr. POST, PUT, PATCH), možete definirati sučelje za tijelo zahtjeva i koristiti ga u tipu Request:

import express, { Request, Response } from 'express';
import bodyParser from 'body-parser';

const app = express();
const port = 3000;

app.use(bodyParser.json()); // Važno za parsiranje JSON tijela zahtjeva

interface CreateUserRequest {
  firstName: string;
  lastName: string;
  email: string;
}

app.post('/users', (req: Request<any, any, CreateUserRequest>, res: Response) => {
  const { firstName, lastName, email } = req.body;

  // Validacija tijela zahtjeva
  if (!firstName || !lastName || !email) {
    return res.status(400).send('Missing required fields.');
  }

  // Obrada stvaranja korisnika (npr. spremanje u bazu podataka)
  console.log(`Creating user: ${firstName} ${lastName} (${email})`);

  res.status(201).send('User created successfully.');
});

app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
});

U ovom primjeru:

• CreateUserRequest definira strukturu očekivanog tijela zahtjeva.
• app.use(bodyParser.json()) je ključno za parsiranje JSON tijela zahtjeva. Bez toga, req.body će biti nedefiniran.
• Tip Request je sada Request<any, any, CreateUserRequest>, što označava da tijelo zahtjeva treba biti u skladu sa sučeljem CreateUserRequest.

TypeScript će sada osigurati da objekt req.body sadrži očekivana svojstva (firstName, lastName i email) i da su njihovi tipovi ispravni. To značajno smanjuje rizik od pogrešaka tijekom izvođenja uzrokovanih netočnim podacima u tijelu zahtjeva.

Rukovanje parametrima rute

Za rute s parametrima (npr. /users/:id), možete definirati sučelje za parametre rute i koristiti ga u tipu Request:

import express, { Request, Response } from 'express';

const app = express();
const port = 3000;

interface UserParams {
  id: string;
}

interface User {
  id: string;
  firstName: string;
  lastName: string;
  email: string;
}

const users: User[] = [
  { id: '1', firstName: 'John', lastName: 'Doe', email: 'john.doe@example.com' },
  { id: '2', firstName: 'Jane', lastName: 'Smith', email: 'jane.smith@example.com' },
];

app.get('/users/:id', (req: Request<UserParams>, res: Response) => {
  const userId = req.params.id;

  const user = users.find(u => u.id === userId);

  if (!user) {
    return res.status(404).send('User not found.');
  }

  res.json(user);
});

app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
});

U ovom primjeru:

• UserParams definira strukturu parametara rute, određujući da parametar id treba biti string.
• Tip Request je sada Request<UserParams>, što označava da objekt req.params treba biti u skladu sa sučeljem UserParams.

TypeScript će sada osigurati da svojstvo req.params.id postoji i da je tipa string. To pomaže u sprječavanju pogrešaka uzrokovanih pristupanjem nepostojećim parametrima rute ili njihovim korištenjem s netočnim tipovima.

Specificiranje tipova odgovora

Iako je fokus na sigurnosti tipa zahtjeva ključan, definiranje tipova odgovora također poboljšava jasnoću koda i pomaže u sprječavanju nedosljednosti. Možete definirati tip podataka koje šaljete natrag u odgovoru.

import express, { Request, Response } from 'express';

const app = express();
const port = 3000;

interface User {
  id: string;
  firstName: string;
  lastName: string;
  email: string;
}

const users: User[] = [
  { id: '1', firstName: 'John', lastName: 'Doe', email: 'john.doe@example.com' },
  { id: '2', firstName: 'Jane', lastName: 'Smith', email: 'jane.smith@example.com' },
];

app.get('/users', (req: Request, res: Response<User[]>) => {
    res.json(users);
});

app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
});

Ovdje, Response<User[]> specificira da tijelo odgovora treba biti niz objekata User. To pomaže osigurati da dosljedno šaljete ispravnu strukturu podataka u odgovorima vašeg API-ja. Ako pokušate poslati podatke koji nisu u skladu s tipom User[], TypeScript će izdati upozorenje.

Sigurnost tipa međuopreme

Funkcije međuopreme ključne su za rukovanje zajedničkim aspektima u Express.js aplikacijama. Osiguravanje sigurnosti tipa u međuopremi jednako je važno kao i u rukovateljima ruta.

Tipiziranje funkcija međuopreme

Osnovna struktura funkcije međuopreme u TypeScriptu slična je onoj rukovatelja ruta:

import express, { Request, Response, NextFunction } from 'express';

function authenticationMiddleware(req: Request, res: Response, next: NextFunction) {
  // Logika autentikacije
  const isAuthenticated = true; // Zamijenite stvarnom provjerom autentikacije

  if (isAuthenticated) {
    next(); // Nastavite na sljedeću međuopremu ili rukovatelja ruta
  } else {
    res.status(401).send('Unauthorized');
  }
}

const app = express();
const port = 3000;

app.use(authenticationMiddleware);

app.get('/', (req: Request, res: Response) => {
  res.send('Hello, authenticated user!');
});

app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
});

U ovom primjeru:

• NextFunction je tip koji pruža Express.js i predstavlja sljedeću funkciju međuopreme u lancu.
• Funkcija međuopreme uzima iste objekte Request i Response kao rukovatelji ruta.

Proširivanje objekta zahtjeva

Ponekad ćete možda htjeti dodati prilagođena svojstva objektu Request u vašoj međuopremi. Na primjer, međuoprema za autentikaciju mogla bi dodati svojstvo user objektu zahtjeva. Da biste to učinili na tipski siguran način, trebate proširiti sučelje Request.

import express, { Request, Response, NextFunction } from 'express';

interface User {
  id: string;
  username: string;
  email: string;
}

// Proširite sučelje Request
declare global {
  namespace Express {
    interface Request {
      user?: User;
    }
  }
}

function authenticationMiddleware(req: Request, res: Response, next: NextFunction) {
  // Logika autentikacije (zamijenite stvarnom provjerom autentikacije)
  const user: User = { id: '123', username: 'johndoe', email: 'john.doe@example.com' };
  req.user = user; // Dodajte korisnika u objekt zahtjeva
  next(); // Nastavite na sljedeću međuopremu ili rukovatelja ruta
}

const app = express();
const port = 3000;

app.use(authenticationMiddleware);

app.get('/', (req: Request, res: Response) => {
  const username = req.user?.username || 'Guest';
  res.send(`Hello, ${username}!`);
});

app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
});

U ovom primjeru:

• Koristimo globalnu deklaraciju za proširivanje sučelja Express.Request.
• Dodajemo opcionalno svojstvo user tipa User sučelju Request.
• Sada možete pristupiti svojstvu req.user u vašim rukovateljima ruta bez da se TypeScript žali. Znak ? u req.user?.username ključan je za rukovanje slučajevima kada korisnik nije autenticiran, sprječavajući potencijalne pogreške.

Najbolje prakse za integraciju TypeScripta i Expressa

Kako biste maksimizirali prednosti TypeScripta u vašim Express.js aplikacijama, slijedite ove najbolje prakse:

• Omogućite strogi način rada: Koristite opciju "strict": true u vašoj datoteci tsconfig.json kako biste omogućili sve opcije stroge provjere tipa. To pomaže u ranom otkrivanju potencijalnih pogrešaka i osigurava višu razinu sigurnosti tipa.
• Koristite sučelja i alias-e tipova: Definirajte sučelja i alias-e tipova za predstavljanje strukture vaših podataka. To čini vaš kod čitljivijim i održivijim.
• Koristite generičke tipove: Iskoristite generičke tipove za stvaranje višekratnih i tipski sigurnih komponenti.
• Pišite jedinične testove: Pišite jedinične testove kako biste provjerili ispravnost vašeg koda i osigurali da su vaše bilješke tipova točne. Testiranje je ključno za održavanje kvalitete koda.
• Koristite linter i formatter: Koristite linter (poput ESLinta) i formatter (poput Prettiera) za provođenje dosljednih stilova kodiranja i hvatanje potencijalnih pogrešaka.
• Izbjegavajte tip any: Minimizirajte upotrebu tipa any, jer on zaobilazi provjeru tipa i poništava svrhu korištenja TypeScripta. Koristite ga samo kada je apsolutno neophodno i razmislite o korištenju specifičnijih tipova ili generičkih tipova kad god je to moguće.
• Strukturirajte svoj projekt logički: Organizirajte svoj projekt u module ili mape na temelju funkcionalnosti. To će poboljšati održivost i skalabilnost vaše aplikacije.
• Koristite injekciju ovisnosti: Razmislite o korištenju spremnika za injekciju ovisnosti za upravljanje ovisnostima vaše aplikacije. To može učiniti vaš kod testabilnijim i održivijim. Knjižnice poput InversifyJS su popularni izbori.

Napredni TypeScript koncepti za Express.js

Korištenje dekoratora

Dekoratori pružaju sažet i izražajan način dodavanja metapodataka klasama i funkcijama. Dekoratore možete koristiti za pojednostavljenje registracije ruta u Express.js-u.

Prvo, morate omogućiti eksperimentalne dekoratore u vašoj datoteci tsconfig.json dodavanjem "experimentalDecorators": true u compilerOptions.

{
  "compilerOptions": {
    "target": "es6",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "experimentalDecorators": true
  }
}

Zatim možete stvoriti prilagođeni dekorator za registraciju ruta:

import express, { Router, Request, Response } from 'express';

function route(method: string, path: string) {
  return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
    if (!target.__router__) {
      target.__router__ = Router();
    }

    target.__router__[method](path, descriptor.value);
  };
}

class UserController {
  @route('get', '/users')
  getUsers(req: Request, res: Response) {
    res.send('List of users');
  }

  @route('post', '/users')
  createUser(req: Request, res: Response) {
    res.status(201).send('User created');
  }

  public getRouter() {
    return this.__router__;
  }
}

const userController = new UserController();

const app = express();
const port = 3000;

app.use('/', userController.getRouter());

app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
});

U ovom primjeru:

• Dekorator route uzima HTTP metodu i putanju kao argumente.
• Registrira dekoriranu metodu kao rukovatelja rute na ruteru povezanom s klasom.
• To pojednostavljuje registraciju ruta i čini vaš kod čitljivijim.

Korištenje prilagođenih čuvara tipova

Čuvari tipova su funkcije koje sužavaju tip varijable unutar određenog opsega. Možete koristiti prilagođene čuvare tipova za provjeru valjanosti tijela zahtjeva ili parametara upita.

interface Product {
    id: string;
    name: string;
    price: number;
}

function isProduct(obj: any): obj is Product {
    return typeof obj === 'object' &&
           obj !== null &&
           typeof obj.id === 'string' &&
           typeof obj.name === 'string' &&
           typeof obj.price === 'number';
}

import express, { Request, Response } from 'express';
import bodyParser from 'body-parser';

const app = express();
const port = 3000;

app.use(bodyParser.json());

app.post('/products', (req: Request, res: Response) => {
    if (!isProduct(req.body)) {
        return res.status(400).send('Invalid product data');
    }

    const product: Product = req.body;
    console.log(`Creating product: ${product.name}`);
    res.status(201).send('Product created');
});

app.listen(port, () => {
    console.log(`Server running at http://localhost:${port}`);
});

U ovom primjeru:

• Funkcija isProduct je prilagođeni čuvar tipa koji provjerava je li objekt u skladu sa sučeljem Product.
• Unutar rukovatelja rute /products, funkcija isProduct koristi se za provjeru valjanosti tijela zahtjeva.
• Ako je tijelo zahtjeva valjani proizvod, TypeScript zna da je req.body tipa Product unutar if bloka.

Rješavanje globalnih razmatranja u dizajnu API-ja

Prilikom dizajniranja API-ja za globalnu publiku, treba uzeti u obzir nekoliko čimbenika kako bi se osigurala pristupačnost, upotrebljivost i kulturna osjetljivost.

• Lokalizacija i internacionalizacija (i18n i L10n):
  • Pregovaranje o sadržaju: Podržite više jezika i regija putem pregovaranja o sadržaju na temelju zaglavlja Accept-Language.
  • Formatiranje datuma i vremena: Koristite ISO 8601 format za prikaz datuma i vremena kako biste izbjegli dvosmislenost u različitim regijama.
  • Formatiranje brojeva: Rukujte formatiranjem brojeva prema lokalizaciji korisnika (npr. decimalni separatori i separatori tisućica).
  • Rukovanje valutama: Podržite više valuta i po potrebi pružite informacije o tečaju.
  • Smjer teksta: Prilagodite se jezicima koji se pišu s desna na lijevo (RTL), kao što su arapski i hebrejski.
• Vremenske zone:
  • Pohranjujte datume i vremena u UTC (Coordinated Universal Time) na strani servera.
  • Dopustite korisnicima da odrede željenu vremensku zonu i sukladno tome pretvorite datume i vremena na strani klijenta.
  • Koristite biblioteke poput moment-timezone za rukovanje konverzijama vremenskih zona.
• Kodiranje znakova:
  • Koristite UTF-8 kodiranje za sve tekstualne podatke kako biste podržali širok raspon znakova iz različitih jezika.
  • Provjerite jesu li vaša baza podataka i drugi sustavi za pohranu podataka konfigurirani za korištenje UTF-8.
• Pristupačnost:
  • Slijedite smjernice za pristupačnost (npr. WCAG) kako biste svoj API učinili dostupnim korisnicima s invaliditetom.
  • Pružite jasne i opisne poruke o pogreškama koje su lako razumljive.
  • Koristite semantičke HTML elemente i ARIA atribute u svojoj API dokumentaciji.
• Kulturna osjetljivost:
  • Izbjegavajte korištenje kulturno specifičnih referenci, idioma ili humora koji možda neće biti razumljivi svim korisnicima.
  • Budite svjesni kulturnih razlika u stilovima komunikacije i preferencijama.
  • Razmislite o potencijalnom utjecaju vašeg API-ja na različite kulturne skupine i izbjegavajte perpetuiranje stereotipa ili predrasuda.
• Privatnost i sigurnost podataka:
  • Pridržavajte se propisa o privatnosti podataka kao što su GDPR (Opća uredba o zaštiti podataka) i CCPA (California Consumer Privacy Act).
  • Implementirajte snažne mehanizme autentikacije i autorizacije za zaštitu korisničkih podataka.
  • Šifrirajte osjetljive podatke u prijenosu i u mirovanju.
  • Pružite korisnicima kontrolu nad njihovim podacima i omogućite im pristup, izmjenu i brisanje njihovih podataka.
• API dokumentacija:
  • Pružite sveobuhvatnu i dobro organiziranu API dokumentaciju koja je lako razumljiva i navigabilna.
  • Koristite alate poput Swagggera/OpenAPI-ja za generiranje interaktivne API dokumentacije.
  • Uključite primjere koda u više programskih jezika kako biste zadovoljili raznoliku publiku.
  • Prevedite svoju API dokumentaciju na više jezika kako biste dosegli širu publiku.
• Rukovanje pogreškama:
  • Pružite specifične i informativne poruke o pogreškama. Izbjegavajte generičke poruke o pogreškama poput "Nešto je pošlo po zlu."
  • Koristite standardne HTTP statusne kodove za označavanje tipa pogreške (npr. 400 za Loš zahtjev, 401 za Neautorizirano, 500 za Internu pogrešku poslužitelja).
  • Uključite kodove pogrešaka ili identifikatore koji se mogu koristiti za praćenje i otklanjanje problema.
  • Zabilježite pogreške na strani poslužitelja za otklanjanje pogrešaka i nadzor.
• Ograničenje broja zahtjeva (Rate Limiting): Implementirajte ograničenje broja zahtjeva kako biste zaštitili svoj API od zlouporabe i osigurali pravedno korištenje.
• Verzioniranje: Koristite verzioniranje API-ja kako biste omogućili unatrag kompatibilne promjene i izbjegli prekid rada postojećih klijenata.

Zaključak

Integracija TypeScripta i Expressa značajno poboljšava pouzdanost i održivost vaših pozadinskih API-ja. Korištenjem sigurnosti tipa u rukovateljima ruta i međuopremi, možete rano uhvatiti pogreške u procesu razvoja i izgraditi robusnije i skalabilnije aplikacije za globalnu publiku. Definiranjem tipova zahtjeva i odgovora osiguravate da se vaš API pridržava dosljedne strukture podataka, smanjujući vjerojatnost pogrešaka tijekom izvođenja. Ne zaboravite se pridržavati najboljih praksi poput omogućavanja strogog načina rada, korištenja sučelja i alias-a tipova te pisanja jediničnih testova kako biste maksimizirali prednosti TypeScripta. Uvijek uzmite u obzir globalne čimbenike poput lokalizacije, vremenskih zona i kulturne osjetljivosti kako biste osigurali da su vaši API-ji dostupni i upotrebljivi širom svijeta.